'''Miscellaneous tools for working with BibTeX strings, mostly for
converting between latex and other formats.

@todo: add module level documentation.

@copyright: (c) 2004-2009, Jim Pitman, Dept. Statistics, U.C. Berkeley
    <http://www.stat.berkeley.edu/users/pitman>
@copyright: (c) 2009-2010, Benjamin Kalish

@license:
    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful, but
    WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    General Public License for more details.
'''

import re
import string

from bkn.bibtex.latex_converter.latex2ascii_converter \
    import Latex2ASCIIConverter
from bkn.bibtex.latex_converter.latex2html_converter \
    import Latex2HTMLConverter
from bkn.bibtex.latex_converter.latex2unicode_converter \
    import Latex2UnicodeConverter


def blank(text):
    '''Returns True if C{text} is C{None} or contains only whitespace.
    
    @param text: the string to test
    @type text: C{str}
    @rtype: C{bool}
    @returns:
        C{True} if C{text} is C{None} or contains only whitespace,
        C{False} otherwise.
    @raise AttributeError:
        blank() will raise an error if its input doesn't act like a
        string. (In particular, it must respond to the strip() method.
    '''
    
    if text is None or text.strip() == '': return True
    return False

def dehyphenate_words(text):
    '''Strips hyphens from hypenated words, ignoring, as much as
    possible, hyphens in other contexts.

    This method removes only single hyphens between alphabetic
    characters. Removed hyphens are replaced with a space.
    '''
    # This regular expression affects only single hyphens; multiple
    # consecutive hyphens, which indicate dashes in LaTeX, will be
    # ignored.
    return re.sub(r'([a-zA-Z])-([a-zA-Z])', r'\1 \2', text)

def strip_punctuation(text):
    '''Strips punctuation from the supplied string.'''
    chars =  [c for c in text if not c in string.punctuation]
    return ''.join(chars)

LATEX_2_ASCII_CONVERTER = Latex2ASCIIConverter()
'''A L{Latex2ASCIIConverter} instance.
@type: L{Latex2ASCIIConverter}
'''

def tex2ascii(tex):
    '''Convert TeX accents, math expressions, etc. to ASCII.
    
    This function is simply a convenient wrapper for the methods provided
    in the bkn.bibtex.latex_converter package.
    
    @param tex: the TeX or LaTeX code to be converted.
    @type tex: C{str}
    @rtype: C{str}
    @return:
        a human readable representation of the string produced by using
        ASCII characters in place of LaTeX code where possible. Note that
        while this string consists only of ascii characters, it is still
        represented as Unicode internally!
    @warning: this is an inherently lossy conversion
    @todo: add real world examples to the documentation for this method
    '''
    # the .encode('ascii') should not be neccesary, but it is best to be safe!
    return LATEX_2_ASCII_CONVERTER.convert(tex)

LATEX_2_HTML_CONVERTER = Latex2HTMLConverter()
'''A L{Latex2HTMLConverter} instance.
@type: L{Latex2HTMLConverter}
'''

def tex2html(tex):
    '''Convert TeX accents, math expressions, etc. to HTML.
    
    @note:
        This function is simply a convenient wrapper for the methods
        provided in the bkn.bibtex.latex_converter package.
    @param tex: the TeX or LaTeX code to be converted.
    @type tex: C{str}
    @rtype: C{str}
    @return:
        a human readable representation of the string produced by using
        HTML code in place of LaTeX code where possible.
    @warning: this is an inherently lossy conversion
    @todo: add real world examples to the documentation for this method
    '''
    return LATEX_2_HTML_CONVERTER.convert(tex)

LATEX_2_UNICODE_CONVERTER = Latex2UnicodeConverter()
'''A L{Latex2UnicodeConverter} instance.
@type: L{Latex2UnicodeConverter}
'''

def tex2unicode(tex):
    '''Convert TeX accents, math expressions, etc. to Unicode.
    
    This function is simply a convenient wrapper for the methods provided
    in the bkn.bibtex.latex_converter package.
 
    @param tex: the TeX or LaTeX code to be converted.
    @type tex: C{str}
    @rtype: C{str}
    @return:
        a human readable representation of the string produced by using
        Unicode characters in place of LaTeX code where possible.
    @warning: this is an inherently lossy conversion
    @todo: add real world examples to the documentation for this method
    '''
    return LATEX_2_UNICODE_CONVERTER.convert(tex)